Night Owl 9

home *** CD-ROM | disk | FTP | other *** search

/ Night Owl 9 / Night Owl CD-ROM (NOPV9) (Night Owl Publisher) (1993).ISO / 040a / 1st_110b.zip / INSTALL.DOC < prev next >

Wrap

Text File | 1993-05-15 | 62KB | 1,776 lines

┌──────────────────────────────────────────────────────────────────┐ │ │ │ │ │ ┌────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ▄██ │ │ │ │ ██ ▄▄▄▄▄▄ ▄▄▄▄▄▄ │ │ │ │ ██ ██▀▀▀▀ ▀▀██▀▀ │ │ │ │ ██ ▀▀▀▀██ ██ │ │ │ │ ██ ██████ ██ │ │ │ │ │ │ │ │ 1stReader INSTALL Module │ │ │ │ │ │ │ │ │ │ │ │ Entire work │ │ │ │ Copyright 1993 by Mark Herring │ │ │ │ All Rights Reserved │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ Sparkware │ │ │ │ Post Office Box 386 │ │ │ │ Hendersonville, Tennessee 37077 │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └────────────────────────────────────────────────────┘ │ │ │ │ │ └──────────────────────────────────────────────────────────────────┘ TABLE OF CONTENTS Scope of this manual.................................... 2 Why an INSTALL utility?................................. 2 INSTALL specifications.................................. 3 @Variables supported by INSTALL......................... 4 INSTALL script commands................................. 4 ADD............................................. 4 ASSIGN.......................................... 6 ATTRIBUTE....................................... 6 BDUMP........................................... 7 BEEP............................................ 7 BLINK........................................... 7 BLIP............................................ 7 BLOAD........................................... 8 BOX............................................. 8 CALL............................................ 8 CGA............................................. 9 CHDIR........................................... 9 CLEAR_BOXES..................................... 9 CLOSE........................................... 9 CLS............................................. 9 COLOR........................................... 10 COMPARE......................................... 10 COPY............................................ 10 CURSOR.......................................... 10 DCHECK.......................................... 10 DIALOG_BOX...................................... 11 DISPLAY......................................... 11 EGA............................................. 11 EOF............................................. 12 EXIST........................................... 12 EXIT............................................ 12 F5.............................................. 12 FILLSCRN........................................ 12 FONT............................................ 13 GET............................................. 13 GOSUB........................................... 13 GOTO............................................ 13 GREATER......................................... 13 INSTR........................................... 14 IF ... THEN .................................... 14 KEYHIT.......................................... 14 KILL............................................ 14 LASTKEY......................................... 15 LESS............................................ 15 LIST............................................ 15 LIST_COLORS..................................... 15 LOAD_API........................................ 16 LOCATE.......................................... 16 LPRINT.......................................... 16 LPRINT_FILE..................................... 16 MKDIR........................................... 17 MREAD........................................... 17 MPU401.......................................... 17 NAME............................................ 17 ON.............................................. 18 OPEN............................................ 18 PAINTBOX........................................ 18 PAUSE........................................... 18 PICK............................................ 19 PLAY............................................ 19 PLAY_AVAILABLE.................................. 19 PLAY_FILE....................................... 19 PRINT........................................... 20 PROMPT.......................................... 20 QPRINT.......................................... 20 READ............................................ 21 RETURN.......................................... 21 RUN............................................. 21 SAVER........................................... 21 SCREEN.......................................... 22 SCROLL_DOWN..................................... 22 SCROLL_LEFT..................................... 22 SCROLL_RIGHT.................................... 22 SCROLL_UP....................................... 22 SEEK............................................ 22 SET............................................. 22 SET_LOAD........................................ 23 SET_SAVE........................................ 23 SET_WINDOW...................................... 24 SHELL........................................... 24 SHOW............................................ 24 SLOW............................................ 25 SWITCH.......................................... 25 UNPACK.......................................... 25 VGA............................................. 25 VOC_AVAILABLE................................... 26 VOC_FILE........................................ 26 WRITE........................................... 26 NOTICE This INSTALL module is for the use of Sparkware customers for their own private purposes. If you are a third-party programmer and have written a utility for one our products you may use this INSTALL module to install your products into ours without obtaining prior permission. Anyone can freely distribute .INS scripts created for this utility without prior permission from Sparkware. If you are interested in using this INSTALL module for other products (other than products from Sparkware) please contact us for more information. EXCEPT FOR THE EXPRESS WARRANTY SET FORTH ABOVE, SPARKWARE GRANTS NO OTHER WARRANTIES, EXPRESSED OR IMPLIED, BY STATUE OR OTHERWISE, REGARDING THE DISK, PROGRAMS AND RELATED MATERIALS, THEIR FITNESS FOR ANY PURPOSE, THEIR QUALITY, THEIR MERCHANTABILITY, OR OTHERWISE. THE LIABILITY OF SPARKWARE UNDER THE WARRANTY SET FORTH ABOVE SHALL BE LIMITED TO THE AMOUNT PAID BY THE CUSTOMER FOR THE PRODUCT. IN NO EVENT SHALL SPARKWARE BE LIABLE FOR ANY SPECIAL, CONSEQUENTIAL, OR OTHER DAMAGES FOR BREACH OF WARRANTY. SPARKWARE RESERVES THE RIGHT TO MAKE ANY CHANGES TO THESE PROGRAMS, DOCUMENTATION AND CUSTOMER SUPPORT PLANS AT ANY TIME WITHOUT PRIOR NOTICE. THIS SOFTWARE PROGRAM IS A PROPRIETY PRODUCT OF SPARKWARE AND IS PROTECTED BY COPYRIGHTS AND INTERNATIONAL TREATIES. YOU MUST TREAT THIS SOFTWARE LIKE ANY OTHER COPYRIGHTED MATERIAL, EXCEPT THAT YOU MAY MAKE AN ARCHIVAL COPY OF THE SOFTWARE FOR EACH COPY THAT IS LICENSED TO YOU. YOU MAY NOT DECOMPILE, DISASSEMBLE, REVERSE ENGINEER, COPY, TRANSFER, OR OTHERWISE USE OR MODIFY THIS SOFTWARE EXCEPT AS STATED HEREIN. YOU ARE ALLOWED TO TRY THIS PROGRAM FOR THIRTY (30) DAYS. USE AFTER THIS PERIOD REQUIRES REGISTRATION OF 1STREADER WITH SPARKWARE. 1stReader INSTALL Module Entire work copyright 1993 by Mark Herring All Rights Reserved Sparkware Post Office Box 386 Hendersonville, Tennessee 37077-0386 USA (615) 230-8822 24 hour support bulletin board system (615) 230-MAIL Office (10-12, 1-5 central weekdays) Page 1 Scope of this manual -------------------- This manual documents the 1stReader INSTALL module language. As a user of 1stReader you do NOT need to become familiar with this information. However, if you are a third-party programmer for 1stReader or just an interested user, please read on! Some knowledge of programming is assumed by this manual. Why an INSTALL utility? ----------------------- We could have written a very 'quick and dirty' installation program for 1stReader. But after thinking about just what an installation program is supposed to do for the user, we began thinking about support for 3rd party programmers. It would be nice if 1stReader offered a flexible installation system for their own products. Then we started moving the idea out into a presentation system for bulletin board systems. Why not allow a BBS to 'present itself' with an interactive demo? Soon we realized that the install utility could be an asset to the whole 1stReader concept. Infact, if you ever select a .INS file from the 1stReader file manager (or try to display a WELCOME.INS file, for example) 1stReader automatically transfers control to this utility and executes the script. If you would like an example of this feature select the "1stTutor" button from the 1stReader opening menu. There is quite alot of 'meat' here for everyone. Personally, we're using INSTALL in our offices as a very flexible menuing system. It's possibilities are almost unlimited! The 1stReader INSTALL module language (INSTALL) was modeled after the BASIC computer language. Page 2 INSTALL specifications ---------------------- Maximum number of lines per script.............. 500 Maximum number of variables..................... 100 Maximum number of nested GOSUBs................. 20 Maximum number of nested CALLed scripts......... 20 Maximum number of labels........................ 100 Any blank line of text, any text beginning with the word "REM", ";" or "'" is considered to be a comment and is not included in the number of lines used in a script. INSTALL also preallocates ten variables for your own use. These variables are documented in the ASSIGN command. You can pass install script filenames (.INS files) on the DOS command line. Example: INSTALL GAMES.INS If you do not enter a filename on the DOS command line then the filename "INSTALL.INS" is assumed. The very first line of each INSTALL script must contain the words: SPARKWARE INSTALL SCRIPT This is required so INSTALL can be sure it is working with an installation script. Otherwise, INSTALL will simply list the .INS file using its internal file LIST utility and exit to DOS. Labels ------ Labels are the targets of the GOTO and GOSUB commands. You may have up to 100 labels per script. A label always starts with a colon ":" character and you may not have a command or function on the same line as a label. Page 3 @Variables supported by INSTALL ------------------------------- The following @variables are supported INSTALL at all times: @DATE@ Today's date @SYSDATE@ Today's date @TIME@ Current system time @SYSTIME@ Current system time @DATE5@ Today's date (MM-DD only) @TIME5@ Today's time (HH:MM only) @WEEKDAY@ Day of week (0=Sunday, 1=Monday, etc) @MEMORY@ Amount of free memory available (in K) @CLS@ Clears screen @CLREOL@ Erases to the end of the current line @DRIVE@ Drive started INSTALL from @INSDRIVE@ Drive where the .INS is located @TIMESPEC@ A unique filename made up of today's date and time (MMDDHHMM). INSTALL script commands ----------------------- Command: ADD Syntax: ADD(Variable$,value) Example: ADD(Count$,5) Variable$ is any previously assigned variable. "value" can either be a literal value or another variable. Command: APRINT Syntax: APRINT(Variable$,Row,Col,Color[,MonoColor]) Example: APRINT("This is a test",12,33,-1) APRINT writes a text string to the ROW and COLumn positions on your screen. Variable$ can either be an assigned variable or text. COLOR is the color to display Variable$ on the screen. Setting color to '-1' tells APRINT to use the current color found at ROW,COL. Passing APRINT a COLumn value of '-1' tells APRINT to center Variable$ on your screen. Page 4 You can also pass a fifth parameter to APRINT. The fifth parameter is the color to use if displaying the text on a monochrome system. If you do not include the fifth parameter APRINT always uses the COLOR attribute. You can also call APRINT once with a full list of parameters and then call APRINT passing only the text to print. Example: APRINT ("This is a test",12,20,-1) APRINT ("--------------") When you omit the extra parameters APRINT will increment the last ROW value by one and use the last COLumn and COLOR values. The main difference between APRINT and QPRINT is that APRINT displays Variable$ through the internal ANSI emulator allowing you to use @x color codes while QPRINT displays Variable$ through direct screen writes. Command: ASK Syntax: ASK(Variable$,Row,Col,Length,HiLite[,MonoHiLite,UPPER]) Example: ASK(Name$,10,20,25,112,UPPER) The ASK command accepts input from your keyboard into Variable$. The cursor is positioned at ROW,COLumn (if you set these values to '-1' then ASK will use the current cursor position). LENGTH is the maximum length of the input field. HILITE is the color attribute to use when entering text (we recommend either a '15' (for high intensity white on black) or '112' (for black on white). If you include the "UPPER" parameter then the input will be in UPPER case letters. Page 5 Command: ASSIGN Syntax: ASSIGN(Variable$,SET,"text") Example: ASSIGN(Path$,0,"C:\1ST\"+Filename$) The ASSIGN command assigns a value (either another variable or string text) to Variable$. This command does support 'joining' two strings together using the '+' character. If SET=0 then "text" is simply assigned to Variable$ IF SET<0 then "text" is LSET into a string -SET characters long. If SET>0 then "text" is RSET into a string SET characters long. If Variable$ has not been previously assigned then INSTALL creates a new variable entry in its table. You can have up to 100 active variables. INSTALL pre-initializes these variables for you: Variable Description ──────── ───────────────────────────────────── _YES$ Y _NO$ N _MOUSE$ (Set to -1 if a mouse is available) _PRESS$ Press any key to continue... _UNPACK$ QUNZIP -O _HELP$ (If set to a filespec, when the user presses 'F1', this file is displayed as online help). _PROMPT$ Type 'EXIT' to return to the program (Used when shelling to DOS via 'F5') _SAVER$ Press a key _FORMAT$ Invalid format (Used when trying to load an invalid MIDI file). _COMMAND$ (DOS command parameters passed to INSTALL) Command: ATTRIBUTE Syntax: ATTRIBUTE(Color[,MonoColor]) Example: ATTRIBUTE(48,112) The ATTRIBUTE command will change the color attribute used by the internal ANSI emulator. If you pass INSTALL a MonoColor parameter then INSTALL will use this value if you are using a monochrome system. Page 6 Command: BDUMP Synatx: BDUMP(Variable$[,ScrnNumber]) Example: BDUMP("SCREENS.BIN",2) The BDUMP command will copy the current screen into the file Variable$. If you add a 'ScrnNumber' parameter then INSTALL uses this value as an offset into the Variable$ file. In the above example BDUMP would start writing the current screen at byte location #4001 in the file. Command: BEEP Syntax: BEEP[(Tone,Duration)] Example: BEEP(3000,1) The BEEP command will sound a tone on the PC speaker. If you do not pass parameters to BEEP then (2500,1) will be used as a default value. Command: BLINK Syntax: BLINK <ON|OFF> Example: BLINK ON The BLINK command will not work with monochrome displays. If BLINK OFF is used then you can access 'high intensity' color backgrounds in your setup. BLINK ON resets your system so blinking colors are supported. NOTE: INSTALL always exits by turning BLINK ON. Command: BLIP Syntax: BLIP <button> Example: BLIP 1 BLIP works with the DIALOG_BOX command. It will let you 'blip' a dialog box as if the user selected the dialog box. The idea behind BLIP is to allow you to create demos where your demo actually selects the command, but to the user it looks likey *they* selected it. <button> is the button number assigned by the DIALOG_BOX command. Page 7 Command: BLOAD Synatx: BLOAD(Variable$[,ScrnNumber]) Example: BLOAD("SCREENS.BIN",2) The BLOAD command works in the opposite manner from the BDUMP command. It will read the BINary file Variable$ and load its contents to your screen. You can pass BLOAD an optional 'ScrnNumber' parameter and BLOAD will use this value as an offset into the Variable$ file. Command: BOX Syntax: BOX(ULRow,ULCol,LRRow,LRCol,Color,MonoColor,Frame, Shadow [,Text$,Header$]) Example: BOX(10,10,14,70,48,112,1,1,"Testing...","Option") The BOX command draws a box on your screen. ULRow, ULCol, LRRow and LRCol describe the box boundaries. COLOR and MONOCOLOR are the two attributes to choose from (depending if you are using a color or monochrome display). FRAME can be one of the following values: 1 = single line all around the box 2 = double line all around the box 3 = double line horizontally, single line vertically 4 = single line horizontally, double line vertically If SHADOW is set to '1' then a shadow is added to the box. TEXT$ is optional and if used TEXT$ is centered in the middle of the box. HEADER$ is also optional and if used will be used as the 'name' of the box. Command: CALL Syntax: CALL <Scriptname> Example: CALL SCRIPT2.INS The CALL command lets you call another INSTALL script (.INS). After the script has executed the program returns to the original script at the next statement after the CALL command. Page 8 Function: CGA Syntax: CGA Example: IF CGA THEN GOTO ... This function returns TRUE if the display is at least capable of CGA graphics. Command: CHDIR Syntax: CHDIR Variable$ Example: CHDIR "C:\1ST" The CHDIR command changes the current subdirectory to Variable$. It will also change drives if needed. Command: CLEAR_BOXES Syntax: CLEAR_BOXES There is no argument for the CLEAR_BOXES command. The command will erase any DIALOG_BOXes that have been created earlier. Command: CLOSE Syntax: CLOSE [FileNum] Example: CLOSE 1 The CLOSE command will close a file previously opened by the OPEN command. If you do not pass a file number with the command then ALL open files will be closed. Command: CLS Syntax: CLS[(Color,MonoColor)] Example: CLS(48,112) The CLS command will clear the screen. If you do not pass it parameters then the current screen color is used. Otherwise, you can pass it COLOR and MonoColor values that will be used depending on which monitor type is being used. Page 9 Function: COLOR Syntax: COLOR Example: IF COLOR THEN GOTO ... The COLOR function will return TRUE if the system is using a color monitor. Otherwise, the function returns FALSE. Function: COMPARE Syntax: COMPARE(Variable1$,Variable2$) Example: IF COMPARE(Choice$,1) THEN GOTO ... The COMPARE function will compare any two variable (or even text) values and will set the function to TRUE if the strings are equal. Note that upper/lower case does not matter with this function. Command: COPY Syntax: COPY(FileSpec1$,FileSpec2$) Example: COPY(Manual$,"C:\1ST") The COPY command will copy one file to another file location. You can specify variables or text in this function. Command: CURSOR Syntax: CURSOR <ON|OFF> Example: CURSOR ON The CURSOR command turns the cursor ON or OFF. Command: DCHECK Syntax: DCHECK Variable$ Example: DCHECK Target$ The DCHECK command is used to make sure that a subdirectory entry has a trailing '\' character. If Variable$ does not end with a '\' then one is added to the variable. Page 10 Command: DIALOG_BOX Syntax: DIALOG_BOX(Button#,BoxType,HotKey,Return,Text$,Row, Col,Color,MonoClr,Shadow,HotColor, HotMonoClr) Example: DIALOG_BOX(1,0,0,1,"About",4,51,112,112,1,116,15) The DIALOG_BOX command lets you draw command buttons on the screen for users to select a choice. Button# The number assigned to this button. You may have up to 20 buttons active at one time. BoxType '0' makes a large, three row button. '1' makes a small, one row button. HotKey The keystroke value required to activate this button. Return The value returned to the GET command. Text$ Variable (or text) to display in the box. The first letter of Text$ is also treated as a 'hotkey' too. Row,Col Screen position to draw the box. Color,MonoClr Color attributes to assign to this box. Shadow If set to '1' then draw a shadow. HotColor (and HotMonoClr) The attributes to display the 'hotkey' in the dialog box. Command: DISPLAY Syntax: DISPLAY <ON|OFF> Example: DISPLAY ON The DISPLAY command will turn updating of your screen ON or OFF. You would want to use this command to turn OFF the display while your script draws a screen. Then turn the display back ON to have the screen 'pop' into view. Function: EGA Syntax: EGA Example: IF EGA THEN GOTO ... This function returns TRUE if the display is at least capable of EGA graphics. Page 11 Function: EOF Syntax: EOF(FileNum) Example: IF EOF(1) THEN GOTO ... The EOF function returns TRUE if FileNum has reached the "End of File" position while reading the file. Function: EXIST Syntax: EXIST Variable$ Example: IF EXIST "INSTALL.DOC" THEN GOTO ... The EXIST function returns TRUE if Variable$ file exists. Command: EXIT Syntax: EXIT Example: EXIT The EXIT command has no parameters. It will exit the current script and either return to the CALLing script or exit to DOS. Command: F5 Syntax: F5 <ON|OFF> Example: F5 ON The F5 command enables or disables the SHELL to DOS via the F5 function key. Command: FILLSCRN Syntax: FILLSCRN(ULRow,ULCol,LRRow,LRCol,ASCII Char,Color [,MonoColor]) Example: FILLSCRN(1,1,25,80,32,48,112) The FILLSCRN command fills a portion of your screen with an ASCII character. ULRow, ULCol, LRRow and LRCol describe the screen boundaries. COLOR and MONOCOLOR are the two attributes to choose from (depending if you are using a color or monochrome display). ASCII CHAR is an ASCII character between 0 and 255 to use to fill the screen. Page 12 Command: FONT Syntax: FONT Variable$ Example: FONT "BIGSERIF.FNT" The FONT command loads an EGA/VGA font on to the screen. Note that FONT checks to see if you are using at least an EGA display. Command: GET Syntax: GET(Variable$[,Default,Seconds]) Example: GET(Choice$,1,30) The CHOICE command works with the DIALOG_BOX command described earlier. It will wait until the user makes a selection from the DIALOG_BOXes. If you wish, you can make one of the boxes the default box and you can make GET exit after a certain number of seconds has passed, using the default value as the return value. Command: GOSUB Syntax: GOSUB <label> Example: GOSUB PrintIt The GOSUB command will transfer control of the script to the <label> routine (if <label> is found). The script will continue until a RETURN command is found. Then, execution is returned to the next line after the GOSUB command. You can nest up to 20 GOSUBs at one time. Command: GOTO Syntax: GOTO <label> Example: GOTO Done The GOTO command will transfer control of the script to the <label> routine (if <label> is found). Unlike GOSUB, GOTO will not return back to the next instruction following the GOTO command. Function: GREATER Syntax: GREATER(Variable1$,Variable2$) Example: IF GREATER(Choice$,1) THEN GOTO ... The GREATER function compares two variables (or text strings) and will return TRUE if Variable1$ is greater than Variable2$. Page 13 Function: INSTR Syntax: INSTR(Start,Variable$,Find$) Example: IF INSTR(1,Name$,"1ST") THEN GOTO ... The INSTR function searches Variable$ for Find$ (or text strings). START is the starting position in Variable$ to use when looking for Find$. If Find$ is found in Variable$ then the function returns TRUE. Command: IF ... THEN ... Syntax: IF <value> THEN .... Example: IF CGA THEN BEEP The IF command allows INSTALL to test various conditions and then act depending upon those tested conditions. For a better example of the IF statement study the INSTALL.INS script. Remember, you can also use the "NOT" modifier to test for the opposite condition. Example: IF NOT CGA THEN BEEP Function: KEYHIT Syntax: KEYHIT Example: IF KEYHIT THEN GOTO ... The KEYHIT function tests to see a keystroke was pressed by the user. You can use it to test for certain values and transfer control based on those values. Command: KILL Syntax: KILL Variable$ Example: KILL "TEMP" The KILL command will delete a file from the disk. Page 14 Function: LASTKEY Syntax: LASTKEY Example: IF LASTKEY 27 THEN GOTO ... The LASTKEY function returns the last keystroke pressed by the user. You can use it to test for certain values and transfer control based on those values. Function: LESS Syntax: LESS(Variable1$,Variable2$) Example: IF LESS(Choice$,1) THEN GOTO ... The LESS function compares two variables (or text strings) and will return TRUE if Variable1$ is less than Variable2$. Command: LIST Syntax: LIST Variable$ The LIST command lets you list the file Variable$ (or a text string) using an internal file lister. Command: LIST_COLORS Syntax: LIST_COLORS(Color1,MonoColor1,Color2,MonoColor2) Example: LIST_COLORS(31,15,30,7) The LIST_COLORS command allows you to change the colors used by the internal LIST module. COLOR1 and MONOCOLOR1 are used to set the color of the text while COLOR2 and MONOCOLOR2 are used to set the box border colors. Page 15 Command: LOAD_API Syntax: LOAD_API Variable$ Example: LOAD_API "NEW_API.$$$" The LOAD_API command will load a 1stReader 1.10 API file (Applications Program Interface) so you can have full access to the 1stReader API from INSTALL. By default, INSTALL will automatically load the file API.$$$ if found in the current subdirectory when INSTALL loads. Once the 1stReader API has been loaded you have full access to the @API(),@API&(), @API$(), and @SWITCH() functions. Also, INSTALL uses the color switch used in 1stReader to determine if a color monitor is being used. Also, Sound Blaster support will be controlled by the position of the "Multimedia" switch inside 1stReader. Command: LOCATE Syntax: LOCATE(Row,Col[,SETATTR]) Example: LOCATE(12,40,SETATTR) The LOCATE command positions the cursor at ROW,COLumn. If you use the optional SETATTR parameter then INSTALL will read the color attribute at this location and set the current attribute to this color. Command: LPRINT Syntax: LPRINT Variable$ Example: LPRINT "This is a test" The LPRINT command will print one line of text (or a variable) to your printer. Make sure your printer is turned ON and is ready to print. Command: LPRINT_FILE Syntax: LPRINT_FILE Variable$ Example: LPRINT_FILE "INSTALL.DOC" The LPRINT_FILE command will print the contents of Variable$ to your printer. Make sure your printer is turned ON and is ready to print. Page 16 Command: MKDIR Syntax: MKDIR Variable$ Example: MKDIR "C:\1ST" The MKDIR command will create a subdirectory. You can use a variable or a text string to hold the subdirectory name. Command: MPU401 Syntax: MPU401 <ON|OFF> Example: MPU401 ON The MPU401 command will route all MIDI output to a MPU401 device on your system. If you do not have a MPU401 compatible device connected to port 330h then all MIDI output will be routed through the sound card. Command: MREAD Syntax: MREAD(FileNum,Lines[,Find$]) Example: MREAD(1,20,":START") The MREAD command will display text through the ANSI interpreter. The FILENUM is the number of the file buffer opened using the OPEN command. LINES is the number of lines to read before returning control back to the script. You can also add a third parameter (either a variable or text string) that tells MREAD to begin displaying text after FIND$ was read. If MREAD reads the line of text "@EXIT@" it will exit the current read. Note that you will need to use the EOF() function to test and see if you are finished reading the file. Command: NAME Syntax: NAME Variable1$ AS Variable2$ Example: NAME "INSTALL.DOC" AS "INSTALL.TXT" The NAME command renames a file to another filename. Page 17 Command: ON Syntax: ON Variable$ GOTO ... Example: ON Choice$ GOTO Label1,Label2,Label3,.... The ON command assumes that Variable$ contains a numeric value. If Variable$="1" then ON will transfer control to the label "LABEL1". If Variable$="2" then ON will transfer control to "LABEL2", etc. Command: OPEN Syntax: OPEN(Variable1$,FileNum,Variable2$) Example: OPEN("I",1,"INSTALL.DOC") The OPEN command will open a file for input or output mode. The mode is determined by the first variable (or text string) parameter. Valid values are: "O" Opens Variable2$ for OUTPUT "A" Opens Variable2$ for APPEND "I" Opens Variable2$ for INPUT "B" Opens Variable2$ for BINARY FILENUM contains the file number to assign to this file. Command: PAINTBOX Syntax: PAINTBOX(ULRow,ULCol,LRRow,LRCol,Color[,MonoColor]) Example: PAINTBOX(1,1,25,80,48,112) The PAINTBOX command fills a portion of your screen with a color attribute. ULRow, ULCol, LRRow and LRCol describe the screen boundaries. COLOR and MONOCOLOR are the two attributes to choose from (depending if you are using a color or monochrome display). Unlike FILLSCRN, PAINTBOX only changes the color of the screen - the text is not disturbed. Command: PAUSE Syntax: PAUSE [seconds] Example: PAUSE 10 The PAUSE command will pause execution of the script until a key has been pressed. If you include the optional [seconds] parameter then PAUSE will wait [seconds] for a keystroke and if a key was not pressed then execution continues with the next statement. Page 18 Command: PICK Syntax: PICK(Variable$,Prompt$,Filename$,LRL,DisplayPos, Length1, DataPos,Length2,Color,MonoColr) Example: PICK(V$,"Select:","MODEMS.DAT",102,1,50,51,50,30,7) The PICK command is designed to let you choose a response from a file. The file must be a formatted file with a specific LOGICAL RECORD LENGTH (LRL). VARIABLE$ will receive the response selected from the file. PROMPT$ is the text to display asking the user to select a choice. FILENAME$ contains the name of the file to read. DISPLAYPOS is the byte position in each* record where the displayed text begins. LENGTH1 is length of the display text in bytes. DATAPOS is the byte position in *each* record where the data field begins. LENGTH2 is the length of the data field. Finally, COLOR and MONOCOLOR determine the color of the displayed entries on the screen. Command: PLAY Syntax: PLAY Variable$ Example: PLAY "T120O2G8G8G8G8A8A8G16E16C8C8C16C16D16C16" The PLAY command plays a ANSI music string to your PC's speaker. Function: PLAY_AVAILABLE Syntax: PLAY_AVAILABLE Example: IF PLAY_AVAILABLE THEN GOTO ... The PLAY_AVAILABLE function checks to see if your system contains a Sound Blaster (or compatible) sound card. If the sound card is found then this function returns TRUE. Command: PLAY_FILE Syntax: PLAY_FILE Variable$ Example: PLAY_FILE "DIXIE.MID" The PLAY_FILE command will play a .CMF or .MID file through your sound card. INSTALL will wait until the music has finished playing before continuing to the next script statement. NOTE: This command will not work if your system does not include a sound card. Page 19 Command: PRINT Syntax: PRINT Variable$ Example: PRINT "This is a test" The PRINT command displays Variable$ through the internal ANSI emulator. Command: PROMPT Syntax: PROMPT(Variable$,Row,Seconds,Color[,MonoColor]) Example: PROMPT("Thanks for using INSTALL",12,5,-1) The PROMPT command displays Variable$ centered in a box on ROW and will pause for SECONDS before erasing the box. Command: QPRINT Syntax: QPRINT(Variable$,Row,Col,Color[,MonoColor]) Example: QPRINT("This is a test",12,33,-1) QPRINT writes a text string to the ROW and COLumn positions on your screen. Variable$ can either be an assigned variable or text. COLOR is the color to display Variable$ on the screen. Setting color to '-1' tells QPRINT to use the current color found at ROW,COL. Passing QPRINT a COLumn value of '-1' tells QPRINT to center Variable$ on your screen. You can also pass a fifth parameter to QPRINT. The fifth parameter is the color to use if displaying the text on a monochrome system. If you do not include the fifth parameter QPRINT always uses the COLOR attribute. You can also call QPRINT once with a full list of parameters and then call QPRINT passing only the text to print. Example: QPRINT ("This is a test",12,20,-1) QPRINT ("--------------") When you omit the extra parameters QPRINT will increment the last ROW value by one and use the last COLumn and COLOR values. The main difference between QPRINT and APRINT is that QPRINT displays Variable$ through direct screen writes while APRINT displays Variable$ through the internal ANSI emulator. Page 20 Command: READ Syntax: READ(FileNum,Variable$[,UPPER,TRIM]) Example: READ(1,Name$,TRIM) The READ command will read one line of input from a previously OPENed file into Variable$. You can also use the parameters UPPER (to convert the input to upper case) and TRIM (to trim spaces from the left and right of the string). Command: RETURN Syntax: RETURN [label] Example: RETURN The RETURN command will return control back to the script at the next command *after* the calling GOSUB command. You can optionally return control to a label by placing the label's name on the same line. Command: RUN Syntax: RUN ScriptName$ Example: RUN "SCRIPT2.INS" The RUN command will transfer control to another INSTALL script command. Unlike the CALL command, RUN does not return back to the calling script once execution is complete. Command: SAVER Syntax: SAVER seconds Example: SAVER 180 INSTALL provides an internal screen saver. You can activate the screen saver by using the SAVER command to tell INSTALL how many seconds should pass without keyboard input before saving the screen. If you wish to disable the screen saver just use SAVER 0. The _SAVER$ variable has been provided for you if you wish to change the message displayed after saving the screen. To recall the saved screen press any key. Page 21 Command: SCREEN Syntax: SCREEN(Number,<SAVE|RESTORE>) Example: SCREEN(1,SAVE) The SCREEN command will save the current screen into one of six screen buffers. Command: SCROLL_DOWN,SCROLL_LEFT,SCROLL_RIGHT,SCROLL_UP Syntax: SCROLL_xxxx(ULRow,ULCol,LRRow,LRCol,Lines) Example: SCROLL_DOWN(1,1,25,80,1) The SCROLL_xxxx (DOWN, LEFT, RIGHT or UP) command will scroll a region of the screen by LINES. UlRow, ULCol, LRRow and LRCol describe the scroll box boundaries. Command: SEEK Syntax: SEEK(FileNum,<Byte Position|Variable$>) Example: SEEK(1,4000) The SEEK command will position the file pointer for FILENUM to BYTE POSITION in the file. You can also specify a string Variable$ instead of a byte position and INSTALL will scan the file to locate Variable$ from the current position. If the string was not found the file pointer is restored to the previous position. Command: SET Syntax: SET <VALUE> Variable$ Example: SET SIGNATURE "Sparky" The SET command lets you assign specific values in the 1stReader .SET file. <VALUE> corresponds to one of the following values: CARDNO Calling card number DLCMD Zmodem download command DOWNLOADS Download subdirectory EDITOR DOS text editor LIST DOS file lister MAXBAUDRATE Maximum baud rate ORIGINAL Original message filespec PACKETDIR Mail packets subdirectory PCPACCESS PC Pursuit access telephone number PCPPWRD PC Pursuit password PCPUSERID PC Pursuit user id PHONEBOOK Name of phone book Page 22 PREFIX1 Dialing prefix #1 PREFIX2 Dialing prefix #2 PROGRAMS Programs subdirectory QUOTE Quote character REPDIR Replies mail packet subdirectory REPLY Reply message filespec SERIALPORT Serial port number SIGNATURE User's signature SUFFIX Dialing suffix ULCMD Zmodem upload command WORKDIR Work subdirectory INIT Modem initialization string NEWUSER New user flag ("XX") SETNAME Name of configuration setup If you need to directly store an @API variable literal into one of these entries use the syntax: LITERAL SET <VALUE> Variable$ The LITERAL keyword prevents INSTALL from translating any @API variables. Command: SET_LOAD Syntax: SET_LOAD Variable$ Example: SET_LOAD "1ST.SET" The SET_LOAD command will load a 1stReader .SET file into memory so you can modify it using the SET command. While a .SET file is loaded you also have the ability to use these @variables: @CFG.SERIALPORT@ Serial port @CFG.DOWNLOADS@ Download directory location @CFG.PROGRAMS@ Programs directory location @CFG.WORKDIR@ Work directory location @CFG.NEWUSER@ Returns "XX" if new user @CFG.PHONEBOOK@ Name of phone book Command: SET_SAVE Syntax: SET_SAVE Variable$ Example: SET_SAVE "1ST.SET" The SET_SAVE command will save a 1stReader .SET file into disk that has been previously loaded by SET_LOAD. Page 23 Command: SET_WINDOW Syntax: SET_WINDOW(ULRow,ULCol,LRRow,LRCol) Example: SET_WINDOW(10,10,15,70) The SET_WINDOW command setup up the scrollable region defined by the internal ANSI emulator. Any strings displayed through the ANSI emulator will only affect this region of the screen. Command: SHELL Syntax: SHELL(Variable$[,SCRNSAVE]) Example: SHELL("1ST") The SHELL command will execute a DOS program or batch file from inside INSTALL. If Variable$ is blank (empty) then the user will be taken to DOS where they can type 'EXIT' to return back to INSTALL. The _PROMPT$ variable has been reserved for the prompt that is displayed in a DOS shell in case you wish to change it. If you include the optional SCRNSAVE parameter then INSTALL will not clear the screen before executing the program. You can also use the DOS command line switches /CGA, /EGA and /VGA with your DOS commands. These switches will check to make sure you have at least the monitor display in use on your system before executing the program. If you try to execute a DOS command like: SHELL("NANOGIF EAGLE.GIF /VGA",SCRNSAVE) on an EGA system, INSTALL will not execute the command. Command: SHOW Syntax: SHOW Variable$ [NOSTOP SCRNSAVE] Example: SHOW "WELCOMEG" The SHOW command displays Variable$ (or a text filename) to your screen. SHOW will pause at every full screen or at every @MORE@ or @PAUSE@ command. NOSTOP will force SHOW to display the file without pausing (except for @MORE@ or @PAUSE@). SCRNSAVE will restore the current screen when finished. Page 24 Command: SLOW Syntax: SLOW(<ON|OFF>[,cps]) Example: SLOW(ON,1) The SLOW command will cause text to be displayed through the internal ANSI emulator to 'slow down' to look as if they were being received over a modem. The 'cps' value is the approximate number of characters per 18ths of a second to display on your screen. Command: SWITCH Syntax: SWITCH(Number,<ON|OFF>) Example: SWITCH(10,ON) If you have previously loaded a 1stReader .SET file then the SWITCH command will let you change the value of the 36 switches used by 1stReader. For a complete list of switch numbers in 1stReader see the ADVANCED.DOC file. Command: UNPACK Syntax: UNPACK Variable1$ TO Variable2$ [Mask$] Example: UNPACK "1ST.ZIP" TO "C:\1ST" "*.*" The UNPACK command will unpack a file archive into a subdirectory. If the subdirectory does not exist then INSTALL will create it for you. The _UNPACK$ variable has been provided in case you wish to change the archiver used by INSTALL. By default, this command is "QUNZIP -O ". Function: VGA Syntax: VGA Example: IF VGA THEN GOTO ... This function returns TRUE if the display is at least capable of VGA graphics. Page 25 Function: VOC_AVAILABLE Syntax: VOC_AVAILABLE Example: IF VOC_AVAILABLE THEN GOTO ... The VOC_AVAILABLE function lets you test the computer for a sound card that is capable of playing .VOC files. If a compatible card was found then this function returns TRUE. Command: VOC_FILE Syntax: VOC_FILE Variable$ Example: VOC_FILE "WELCOME.VOC" The VOC_FILE command plays a .VOC file through your sound card. INSTALL will pause until the file is finished playing or you press any key to terminate playback. Command: WRITE Syntax: WRITE(FileNum,Variable$) Example: WRITE(1,"This is a test") The WRITE command will write information to a previously OPENed file. If you are writing to a file that was opened for BINARY mode then a CR/LF is not added to the file. If you wish to write out hexadecimal values you can use the "X'nn" format where "nn" is the value (in hex) to write. Page 26